Skip to content

docs: add end-user tutorials for Krini and CLI - #139

Merged
uniqueg merged 5 commits into
mainfrom
docs/111-end-user-tutorials
Nov 14, 2026
Merged

uniqueg merged 5 commits into
mainfrom
docs/111-end-user-tutorials

Conversation

@uniqueg

@uniqueg uniqueg commented Nov 13, 2026 •

Copy link
Copy Markdown
Member

Summary

Adds two end-user tutorials for researchers, from the first login to the results:

  • docs/researchers/tutorial-krini.md: Tutorial: Your First Run in Krini, in the browser.
  • docs/researchers/tutorial-cli.md: Tutorial: Your First Run from the Command Line, with ga4gh-cli.

Both run the same small demo job (count the lines, words and characters of a public text file) twice: as a TES task and as a WES workflow. Each step does one thing, says what to check, and links to the reference guides for details instead of repeating them: the Krini user guide (#137, docs/researchers/krini.md) and the CLI guide (#136, docs/researchers/cli.md), both merged.

The demo materials are new files in docs/researchers/tutorial-files/: a CWL v1.0 CommandLineTool (count-words.cwl, wc in alpine:3.20) and its parameters (count-words.json). I didn't reuse the classic hashsplitter demo (cwl-WES tests/workflows/workflow.hashsplitter, also in the retired elixir-cloud-demos): it fails with the current kubler/openssl image, whose OpenSSL 3.5 no longer knows the digest sha (dgst: Unknown option or message digest: sha).

Aligned with the merged guides:

  • Krini: the same note as docs: add the Krini user guide #137 (the tutorial describes the new Krini on staging at c81a259). Warnings where the known gaps hit a step: the TEST SERVER entry (krini#67), no result files from the task form (fix(tes): send outputs from the create-run form cloud-components#574), and no run details in Krini, so the WES result is read through the API as the guide describes (krini#66). TES tasks need a service that accepts requests without a token.
  • CLI: like the CLI guide, the tutorial documents only the token variable (oauth_access_token_env); no device-flow login. Binaries are marked as planned (ci: publish CLI binaries on version tags ga4gh/ga4gh-sdk#91). The tutorial offers two ways to get a token: an own LS Login client, or copying it from Krini (if the service accepts it).
  • docs/researchers/index.md: both tutorials listed in "What you can try", after "Use the Command Line". mkdocs.yml: two nav entries at the same place.

A run-through of both tutorials by someone who didn't write them (the last criterion of #111) is welcome, e.g., at the BioHackathon, but doesn't block the merge: both pages say how they were tested and ask readers to report what didn't work.

Verification

On the branch after merging origin/main (c0e5d36, with #135, #136, #137 and #138):

  • python scripts/check_names.py: no findings.
  • mkdocs build --strict: built without warnings (links and anchors to krini.md and cli.md resolve).
  • pytest: 25 passed, coverage 100%.
  • Earlier: cwltool 3.3 with Docker ran count-words.cwl with count-words.json (input fetched from the https URL) and produced counts.txt = 121 1066 7048, which matches wc LICENSE. The TES task's command, wc /data/LICENSE in alpine:3.20, prints the output shown in the tutorials.
  • Not run: the tutorials against a deployed Krini or deployed TES/WES services (no services published for researchers yet, and no token for agents), and the CLI build (the CLI guide in docs: cover CLI tokens, WES and TRS #136 tested the commands at af0e021). Until this PR is merged, the raw GitHub URLs of count-words.cwl and count-words.json on main return 404.

Sourcery review (6 threads): fixed 4 in 28102f5 (warning to send the token only to trusted services, base_path as the registry URL plus the API path where needed, demo files in their own folder, CWL v1.0 as a prerequisite of part 2); the checks above were rerun after the fixes.

Declined review findings

  • Pin the workflow URLs to a commit (Sourcery): the demo files are reviewed with the docs on protected main; a SHA can't be pinned before the squash merge, and each later pin would need a follow-up PR. A tag can replace main if the docs get releases.
  • Add InlineJavascriptRequirement to count-words.cwl (Sourcery): $(inputs.text.path) is a CWL parameter reference, which CWL v1.0 supports without JavaScript; cwltool ran the file as is.

Light lane: docs only (two Markdown pages, two demo files, two index rows, two nav lines); no code, configuration or CI changes. I reviewed the diff myself.

Closes #111

🤖 Generated with Claude Code

Add two task-oriented tutorials for researchers, from the first login
to the results: one for the Krini portal and one for ga4gh-cli. Both
run the same demo job, counting the words of a text file, as a TES
task and as a WES workflow, and link to the Krini and CLI guides for
all details. Add the demo CWL workflow and its parameters, tested
with cwltool.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@sourcery-ai

sourcery-ai Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Reviewer's Guide

Configuration

Review the MkDocs navigation entries for the tutorials alongside their placement in the researcher index.

  • mkdocs.yml L120-121

Documentation

Review the two tutorials together with their shared CWL workflow and parameters: they walk through the same TES task and WES workflow in Krini and ga4gh-cli, including prerequisites, authentication, limitations, results, and cleanup.

  • docs/researchers/tutorial-cli.md L1-350
  • docs/researchers/tutorial-files/count-words.cwl L1-19
  • docs/researchers/tutorial-files/count-words.json L1-6
  • docs/researchers/tutorial-krini.md L1-230

Review how the researcher index introduces and links the new tutorials.

  • docs/researchers/index.md L15-16

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

uniqueg and others added 2 commits November 13, 2026 22:52
Drop the planned device-flow login from the CLI tutorial: the CLI
reference documents only the token variable. Add warnings for the
Krini gaps krini#66, krini#67 and cloud-components#574, and list
both tutorials on the researchers start page.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@read-the-docs-community

read-the-docs-community Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

Documentation build overview

📚 elixir-on-cloud-docs | 🛠️ Build #35880355 | 📁 Comparing 28102f5 against latest (c0e5d36)

  🔍 Preview build  

3 files changed
+ researchers/tutorial-cli/index.html
+ researchers/tutorial-krini/index.html
± researchers/index.html

@uniqueg
uniqueg marked this pull request as ready for review November 13, 2026 22:06
@sourcery-ai

sourcery-ai Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Linked issues

Checked at commit 28102f5

#111 docs: add end-user tutorials for the portal and the CLI · 1 of 2 met · 1 to check by hand

# Requirement Status Notes
1 Write one tutorial each for the portal and the CLI, from first login to results, using the demo materials. ✅ Met The Krini and CLI tutorials cover login through results and use the shared demo workflow and parameters.
2 Both tutorials are published and tested by someone who didn't write them. 👀 Check by hand (runtime) A person who didn't write the tutorials must run both through to the stated results; the PR says neither has yet been run by a non-author.

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey - I've found 6 issues

Prompt for AI Agents
Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="docs/researchers/tutorial-cli.md" line_range="109-111" />
<code_context>
+with their `URL`s. If a service isn't listed, use the address that its
+operators gave you.
+
+Before you send a token to a service, check in the [front end of the Cloud
+Registry][elixir-cloud-registry] that it is verified: the CLI doesn't show
+this.
+
+Then add a `TES` and a `WES` section to `~/.ga4gh-cli/config.json` in a text
</code_context>
<issue_to_address>
**Login tokens reach untrusted services**

When a user relies on a verified Registry label for a service they have not independently trusted, including an unsynced or out-of-sync entry, the CLI sends `LS_LOGIN_TOKEN` to the configured service, so an attacker-controlled endpoint can reuse the bearer token to act as the researcher.

Tell users to independently verify the service endpoint and not treat the Registry's verified label as sufficient assurance before sending a token.
</issue_to_address>

### Comment 2
<location path="docs/researchers/tutorial-krini.md" line_range="154" />
<code_context>
+
+    | Field | Value |
+    |---|---|
+    | **Workflow URL** | `https://raw.githubusercontent.com/elixir-cloud-aai/docs/main/docs/researchers/tutorial-files/count-words.cwl` |
+    | **Workflow Type** | `CWL` |
+    | **Workflow Type Version** | `v1.0` |
</code_context>
<issue_to_address>
**Changed workflow executes remotely**

When an attacker alters or compromises the documentation repository's `main` branch before a user follows either tutorial, krini and `ga4gh-cli` submit the mutable `main`-branch CWL URL to WES, which executes its current contents. A malicious replacement therefore runs attacker-controlled workflow code on the selected service instead of the reviewed demo.

Pin the workflow URLs to an immutable revision and update them when the demo changes.

Also at `docs/researchers/tutorial-cli.md:254`.
</issue_to_address>

### Comment 3
<location path="docs/researchers/tutorial-files/count-words.cwl" line_range="10" />
<code_context>
+  DockerRequirement:
+    dockerPull: alpine:3.20
+baseCommand: wc
+stdin: $(inputs.text.path)
+inputs:
+  text:
</code_context>
<issue_to_address>
**Workflow fails on conforming engines**

When a WES service runs a CWL engine that enforces declared requirements, the CWL document uses the JavaScript expression `$(inputs.text.path)` for `stdin` but declares only `DockerRequirement`; an engine that honors CWL requirement declarations refuses to evaluate it, so the workflow fails before `wc` runs and both tutorials cannot produce their advertised result.

Add `InlineJavascriptRequirement: {}` to the document's `requirements`.
</issue_to_address>

### Comment 4
<location path="docs/researchers/tutorial-krini.md" line_range="143-144" />
<code_context>
+3. Point at the info icon next to the service and check that it supports
+   the workflow type `CWL` in the version `v1.0`.
+
+If no service that you can use runs CWL, ask its operator for an example
+workflow in a language that it runs, and use that in the next step.
+
+### 7. Start the workflow
</code_context>
<issue_to_address>
**Alternate workflows cannot be substituted**

When the available WES service runs another workflow language but not CWL v1.0, the next step still requires the supplied CWL workflow and `CWL` v1.0 settings, so the operator-provided workflow in another language is never used and the run is rejected.

Either make a CWL v1.0 service a strict prerequisite and remove the alternative-language advice, or explain how to substitute the operator’s workflow, language, version, and parameters in each tutorial.

Also at `docs/researchers/tutorial-cli.md:243-244`.
</issue_to_address>

### Comment 5
<location path="docs/researchers/tutorial-cli.md" line_range="196" />
<code_context>
+      "command": ["wc", "/data/LICENSE"]
+    }
+  ]
+}' > count-words-task.json
+TASK_ID=$(ga4gh-cli tes create count-words-task.json)
+echo "$TASK_ID"
</code_context>
<issue_to_address>
**Cleanup deletes users’ existing files**

When two tutorial sessions share a working directory, or either output filename already exists there, the fixed-name redirects and `curl -O` overwrite existing files, and cleanup deletes them; with shared sessions, one session can also remove `count-words.json` before the other reaches `wes run`, so the run cannot start.

Use a separate working directory or unique filenames for each session, and ensure cleanup only removes files created by that session.

Also at `docs/researchers/tutorial-cli.md:252`, `docs/researchers/tutorial-cli.md:296`.
</issue_to_address>

### Comment 6
<location path="docs/researchers/tutorial-cli.md" line_range="125" />
<code_context>
+    "base_path": "https://elixir-on.cloud/ga4gh/registry/v1"
+  },
+  "TES": {
+    "base_path": "https://<TES HOST>/ga4gh/tes/v1",
+    "oauth_access_token_env": "LS_LOGIN_TOKEN"
+  },
</code_context>
<issue_to_address>
**Service URLs become malformed**

When a user substitutes a registry `URL` that already includes `https://` and an API path into `<TES HOST>` or `<WES HOST>`, `base_path` then contains a duplicated scheme or API path because the template also adds those components; `ga4gh-cli` requests fail to reach the service, so the tutorial’s service checks and runs fail.

Tell readers to use the registry URL verbatim as `base_path`, adding an API path only when the URL stops before the API root.

Also at `docs/researchers/tutorial-cli.md:129`.
</issue_to_address>

Sourcery assessment

Approval pending. 6 findings to address first.

Blocking findings: docs/researchers/tutorial-cli.md:111, docs/researchers/tutorial-krini.md:154, docs/researchers/tutorial-files/count-words.cwl:10, docs/researchers/tutorial-krini.md:144, docs/researchers/tutorial-cli.md:196, and 1 more


Sourcery is free for open source - if you like our reviews please consider sharing them ✨

Comment thread docs/researchers/tutorial-cli.md Resolved
Comment thread docs/researchers/tutorial-krini.md Resolved
Comment thread docs/researchers/tutorial-krini.md Resolved
Comment thread docs/researchers/tutorial-cli.md Resolved
Comment thread docs/researchers/tutorial-cli.md Resolved
Warn in the CLI tutorial to send the token only to trusted services,
explain base_path as the registry URL plus the API path where needed,
keep the demo files in their own folder, and make CWL v1.0 a
prerequisite of part 2 in both tutorials.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@uniqueg
uniqueg merged commit a0701c8 into main Nov 14, 2026
17 checks passed
@uniqueg
uniqueg deleted the docs/111-end-user-tutorials branch November 14, 2026 17:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: add end-user tutorials for the portal and the CLI

1 participant